Graphics Plus/Graphics Plus.iso/general/modelers/geomview/source.lha/Geomview/doc/geomview-1

Text File | 1993-12-06 | 51KB | 1,155 lines

Info file: geomview,    -*-Text-*-
produced by texinfo-format-buffer
from file: geomview.tex



File: geomview  Node: Top, Up: (DIR), Next: What

* Menu:

* What::        What is Geomview?.
* Authors::        The Authors of Geomview.
* Register::        Let Us Hear From You.
* Overview::        Overview of Geomview.
* Tutorial::        Introductory Tutorial.
* Interaction::        Interacting with Geomview.
* OOGL File Formats::    Formats for Geometry Input.
* Customization::    Modifying the behavior of Geomview.
* Modules::        Programs that use Geomview for graphics display.
* GCL::            gcl: the Geomview Command Language.
* Mathematica::        Mathematica Graphics in Geomview or RenderMan.
* Installation::    Installing Geomview on your computer.

* Function Index::    A node for each gcl function.


File: geomview  Node: What, Prev: Top, Up: Top, Next: Authors

What Is Geomview?
*****************

Geomview, pronounced GE-om-view, is an interactive program for viewing
and manipulating geometric objects, written by staff members of the
Geometry Center.  It can be used as a standalone viewer for static
objects or as a display engine for other programs which produce
dynamically changing geometry.  It runs on Silicon Graphics (SGI) IRIS
workstatons and NeXT workstations.  This manual describes SGI Geomview
version 1.4.1.  Although we do not yet have a manual for the NeXT
version, much this of manual applies to that version as well as to the
SGI version.

Geomview and this manual are available for free via anonymous ftp on the
Internet from host `geom.umn.edu' (IP address 128.101.25.35).
Permission is granted to make copies of this manual.

If you have questions or comments about Geomview or this manual, you can
email them to `[e-mail]'.  We are always glad to hear from
users.  There is also a `geomview-users' mailing list for announcements
regarding Geomview and for Geomview users to communicate with each
other.  If you use Geomview please send an email note to
`[e-mail]' requesting to be added to this
mailing list.


File: geomview  Node: Authors, Prev: What, Up: Top, Next: Register

Authors
=======

Tamara Munzner, Stuart Levy, and Mark Phillips are the original authors
of Geomview. Celeste Fowler, Charlie Gunn, and Nathaniel Thurston also
made significant contributions.  Daniel Krech and Scott Wisdom did the
NeXTStep and RenderMan port, and Daeron Meyer is currently working on a
port to X windows.

Mark Phillips wrote this manual, with substantial help from Stuart Levy
and Tamara Munzner.  Countless Geomview users have also been of great
help by reading it and pointing out mistakes.


File: geomview  Node: Register, Prev: Authors, Up: Top, Next: Overview

Let Us Hear From You
********************
We are very interested in hearing about how you are using Geomview.
Think of Geometry Center software as a new kind of shareware: you share
your science and successes with us, and we share our software and
support with you.  The Geometry Center is funded by the National Science
Foundation, and it is important that we be able to report to NSF the
ways in which our software is being used.

If you use Geomview, please send us a letter telling us what you are
doing with it. We need to know:

  1. What you are working on - an abstract of your work would be fine.

  2. How Geomview has helped you, for example, by increasing your
     productivity or allowing you to do things you could not do before.  In
     particular, if you feel that Geomview has had a direct bearing on your
     work, please tell us about this.

Please send the letter either via email to `[e-mail]',
or via regular mail to the address below.

Moreover, if you use Geomview or other Geometry Center software in your
work, we encourage you to cite its use in your publications.

Thank you!



     Software Development Group
     Geometry Center
     1300 South 2nd St, Suite 500
     Minneapolis, MN  55454
     USA



File: geomview  Node: Overview, Prev: Register, Up: Top, Next: Tutorial

Overview
********

Geomview's main purpose is to display objects whose geometry is given,
allowing interactive control over details such as point of view, speed
of movement, appearance of surfaces and lines, and so on.  Geomview can
handle any number of objects and allows both separate and collective
control over them.

The simplest way to use Geomview is as a standalone viewer to see
and manipulate objects.  It can display objects described in a variety
of file formats.  It comes with a wide variety of example objects, and
you can create your own objects.

You can also use Geomview to handle the display of data coming from
another program that is running simultaneously.  As the other program
changes the data, the Geomview image reflects the changes.  Programs
that generate objects and use Geomview to display them are called
*external modules*.  External modules can control almost all
aspects of Geomview.  The idea here is that many aspects of the display
and interaction parts of geometry software are independent of the
geometric content and can be collected together in a single piece of
software that can be used in a wide variety of situations.  The author
of the external module can then concentrate on implementing the desired
algorithms and leave the display aspects to Geomview.  Geomview comes
with a collection of sample external modules, and this manual describes
how to write your own.

Geomview represents the current state of an ongoing effort at the
Geometry Center to provide interactive geometry software that is
particularly appropriate for mathematics research and education.  In
particular, Geomview can display things in hyperbolic and spherical
space as well as Euclidean space.

Geomview allows multiple independently controllable objects and
cameras.  It provides interactive control for motion, appearances
(including lighting, shading, and materials), picking on an object,
edge or vertex level, snapshots in SGI image file or Renderman RIB
format, and adding or deleting objects is provided through direct
mouse manipulation, control panels, and keyboard shortcuts.

Geomview supports the following simple data types: polyhedra with
shared vertices (.off), quadrilaterals, rectangular meshes, vectors,
and Bezier surface patches of arbitrary degree including rational
patches. Object hierarchies can be constructed with lists of objects
and instances of object(s) transformed by one or many 4x4 matrices.
Arbitrary portions of changing hierarchies may be transmitted by
creating named references.

Geomview can display Mathematica graphics output.


File: geomview  Node: Tutorial, Prev: Overview, Up: Top, Next: Interaction

Tutorial
********

This chapter leads you through some of the basics of using Geomview.
Work through this chapter in front of a workstation where you can try
out the examples given here to get a feel for what you can do with
Geomview.

To start Geomview, login to the computer and get a shell window.  A
shell window is a window in which you can type unix commands; the prompt
in the window usually ends with a '%'.  In the shell window (the mouse
cursor must be in the window) type the following (`RET' here
means hit the "Enter" key):

     geomview tetra dodec RET

This command starts up Geomview and loads two example objects, a
tetrahedron and a dodecahedron.  After a few seconds three windows
should appear as shown in Figure 1.
(The figures in this document appear only in the hardcopy version,
not the Info version.)

The panel on the left is Geomview's main control panel; it's called
the *Main* panel.  The skinny panel in the middle is the
*Tools* panel and is for selecting different kinds of motions.
The window on the right is the camera window and in it you see a
large tetrahedron and a dodecahedron which is partially obscured
by the tetrahedron.

Geomview has lots of panels but by default it displays only these three.
We'll describe some aspects of these and a couple of the others in this
tutorial.  You can read more about these and other panels in the later
chapters of this manual.

Put the mouse cursor in the camera window and press down and hold the
left mouse button.  Now, while holding down the button, slowly move the
mouse around.  You should see the picture rotate in the direction you
move the mouse.    If you lift up on the mouse button while moving the
mouse, the picture continues rotating.  To stop it, hold the mouse very
still and click down and up on the left mouse button.

Geomview uses the *glass sphere* model for mouse-based motion.  This
means you are supposed to think of the object as being inside an
invisible sphere and the mouse cursor is a gripper outside the sphere.
When you hold down the left mouse button, the gripper grabs the
sphere; when you let go of the button, the gripper releases the
sphere.  Moving the mouse while holding the button down causes the
sphere (and hence the object) to move in the same direction as the
mouse.

In addition to the two solids you should also see two wireframe
boxes in the camera window.  These are the "bounding boxes" of the two
objects.  By default Geomview puts a bounding box around each object
that it displays so that you have an idea of how large it is.

Notice that as you move the mouse around the tetrahedron and
dodecahedron move as a unit.  That is because by default what you are
actually moving is the "World".  To move an individual object instead of
the whole world, move the mouse cursor to the *TARGET* browser in
the *Main* panel.  Click (any button) on the word *tetra*.
This makes the tetrahedron be the "target object".  Now move the cursor
back to the camera window and you can rotate just the tetrahedron.

The motion that you have been applying up to now has been rotation,
because that is the motion mode that is selected in the *Tools*
panel.  To translate instead, click on the *Translate* button.
Now when you move the mouse in the camera window while holding down the
left button, the tetrahedron (which should still be the target object
from before) will translate in the direction you move the mouse.  Notice
that you can translate it beyond the edge of the window as long as you
keep holding the left mouse button down.  If you lift up on the mouse
button while moving the mouse, the tetrahedron will keep going.  It
moves rather rapidly so it is very easy to lose track of where it is.

If you accidentally lose the tetrahedron by translating it too far out
of the view of the window, you can get it back by clicking on the
*Center* button in the *Tools* panel.  This causes it to
come back to its initial position.

Click on the *Center* button to bring the tetrahedron home, and
then translate it off to one side so that you can completely see the
dodecahedron.

Your world now has two objects in it that are beside each other.  You
should see the dodecahedron in the middle of the window and maybe part
of the tetrahedron off to one side.  Go back to the *TARGET*
browser in the *Main* panel and click on "World" to select the
whole world again.  Now click on the *Look At* button in the
*Tools* panel.  You should see something like Figure 2 --- the
dodecahedron and the tetrahedron in the middle of the window next
to each other.  The *Look At* button positions the camera in
such a way that the target object is centered in the window.

Now put the cursor over the middle of the dodecahedron and double-click
the right mouse button.  This means click it down-and-up two times in
rapid succession.  Notice that the dodecahedron becomes the target
object; you can see this in the *TARGET* browser in the
*Main* panel.  Double-clicking the right mouse button on an object
is another way to make it the target object.

Go to the *PANELS* browser in the *Main* panel and click on
the word *Appearance*.  This brings up the *Appearance*
panel.  When it appears, if it partially obscures another Geomview window
you can move it off to one side by dragging its frame with the middle
mouse button down.

The *Appearance* panel lets you control various things about the
way Geomview draws objects.  In the upper right corner, under the
*Done* button are buttons labeled *[af] Faces* and
*[ae] Edges*.  Click on the *[ae] Edges* one, and notice
that Geomview is now drawing the edges of the dodecahedron.  Click on it
again and the edges go away.  Click several times and watch the edges
come and go.  When you've had enough of this, leave the edges on
and click the *[af] Faces* button.  This toggles the faces
on and off.  Click the button again to turn them back on.

Now click on the *[Cf] Faces* button under the word
*COLOR*.   A color chooser panel like the one in Figure
4 should appear.
Put the cursor in the color hexagon in this panel and hold down the left
mouse button.  Slowly move the mouse around.  This drags the little
black point around to choose a new color for the dodecahedron.  The
previous colors were specified in the file `dodec' that you loaded
when we started Geomview.  The color that you specify with the color
panel overrides the old colors.  You can adjust the intensity of the
color with the *Intensity* slider.  When you find a color that
you like, click the *OK* button.


Now put the cursor somewhere over the gray background and double-click
the right mouse button; this picks "World" as the target object.
Click the *Look At* button to look at the world again.

Notice that in the *Appearance* panel the settings of the buttons
have changed from the way you left them with the dodecahedron.  That's
because the *Appearance* panel always displays the settings for
the target object, which is now the world, which still has its
default settings.

Click on the *[ab] BBox* button under the word *Draw*.
The bounding boxes go away.  Now put the cursor back in the camera
window.  At the keyboard, type the keys `a b'.  Notice that the
bounding boxes come back.  `a b' is the keyboard shortcut for
the bounding box toggle button; the string "[ab]" appears on the
button to indicate this.  Most of Geomview's buttons have keyboard
shortcuts that you can use instead if you want.  This is useful once
you are familiar with Geomview and don't want to have to move around
among lots of panels.

Now select the tetrahedron, either by double-clicking the right mouse
button on it, or by selecting "tetra" in the *TARGET* browser.
Then click on the *Delete* button in the *Main* panel.  The
tetrahedron should disappear.  This is how you get rid of an object.

You can also load objects from within Geomview.  Click on the *Load*
button in the main panel.  The *Files* panel will appear.
Near the top of this panel is a browser with three lines in it; the
second line is a directory with lots of Geomview example files
in it.  Click on that second line.  Your *Files* panel should
then look something like Figure 5.  Scroll down in the list of files
until you see `tref.off'.  Click on that line, and then click
on the *Add* button.  A large trefoil-shaped tube will appear
in your window.  Click the *Done* button in the *Files*
panel to dismiss the panel.


Now click on the *Reset* button in the *Tools* panel.  This
causes everything to return to its home position.  You should see
something like Figure 6 at this point: a dodecahedron and a
trefoil knot.

Play around with the trefoil knot and the dodecahedron.  Experiment with
some of the other buttons in the *Tools* panel.  Try coloring the
trefoil knot with the *Appearance* panel.

For a tutorial on how to create your own objects to load into Geomview,
see file `doc/oogltour' distributed with Geomview
(`/u/gcg/ngrap/doc/oogltour' on the Geometry Center system).  The
things in that file will be incorporated into a future version of this
manual.



File: geomview  Node: Interaction, Prev: Tutorial, Up: Top, Next: Starting Geomview

Interaction
***********

This chapter describes how you interact with Geomview through the
mouse and keyboard.

* Menu:

* Starting Geomview::             Starting Geomview.
* Command Line Options::          Command Line Options.
* Basic Interaction::             Basic Interaction: The Main Panel.
* Loading::                       Loading Objects Into Geomview.
* Mouse Motions::                 Using the Mouse to Manipulate Objects.
* Appearance::                    Changing the Way Things Look.
* Cameras::                       Cameras.
* Saving::                        Saving your work.
* Command Obscure::               The Commands and Obscure Panels.
* Keyboard Shortcuts::            Keyboard Shortcuts.


File: geomview  Node: Starting Geomview, Prev: Interaction, Up: Interaction, Next: Command Line Options

Starting Geomview
=================

The usual way to start Geomview is to type `geomview RET' in a shell
window (RET means hit the "Enter" key).  It may take Geomview a few
seconds to start up; one or more windows will appear and you can begin
interacting with Geomview immediately.

It is also possible to specify actions for Geomview to perform at
startup time by giving arguments in the shell command line.
*Note Command Line Options::.



File: geomview  Node: Command Line Options, Prev: Starting Geomview, Up: Interaction, Next: Basic Interaction

Command Line Options
====================

Here are the command line options that Geomview allows:

`-b R G B'
     Set the window background color to the given R G B
     values.

`-c FILE'
     Interpret the gcl commands in FILE, which may be the special
     symbol `-' for standard input.  For a description of gcl,
     *Note GCL::.

`-c COMMAND'
     Commands may also be supplied literally, as in
          -c "(ui-panel main off)"
     Since COMMAND includes parentheses, which have special meaning to
     the shell, COMMAND must be quoted.

`-wins NWINS'
     Causes Geomview to initially display NWINS camera windows.

`-wpos WIDTH,HEIGHT[@XMIN,YMIN]'
     Specifies the initial location and size of the first camera window.  The
     values for WIDTH, HEIGHT, XMIN, and YMIN are in
     screen (pixel) coordinates.

`-wpos -'
     You are prompted for placement of the first camera window.

`-M OBJECTNAME'
     Display (possibly dynamically changing) geometry sent from the
     `geomstuff' program.  This actually listens to the
     named pipe `/tmp/geomview/objectname'; you can achieve the same
     effect with the shell commands:
          mkdir /tmp/geomview
          mknod /tmp/geomview/objectname p
     (assuming the directory and named pipe don't already exist), then
     executing the gcl command:
     `(geometry objectname  < /tmp/geomview/objectname)'

`-Mc PIPENAME'
     Like `-M' above, but expects gcl commands, rather than OOGL
     geometry data, on the connection.

`-nopanels'
     Start up displaying no panels, only graphics windows.  Panels may be
     invoked later as usual with the `Px' keyboard shortcuts or with
     the `ui-panel' command.

`-e MODULE'
     Start an external module; MODULE is the name associated with the
     module, appearing in the main panel's Applications browser, as defined
     by the `emodule-define' command.

`-start MODULE ARGS ...'
     Like -e but allows you to pass arguments to the external module.  "--"
     signals the end of the argument list; the "--" may be omitted if it
     would be the last argument on the Geomview command line.

`-run SHELL-COMMAND ARGS ...'
     Like -start but takes the pathname of executable of the external module
     instead of the module's name.



File: geomview  Node: Basic Interaction, Prev: Command Line Options, Up: Interaction, Next: Loading

Basic Interaction: The Main Panel
=================================

Normally when you invoke Geomview, three windows appear: the
*Main* panel, the *Tools* panel, and one camera window.
Geomview has many other windows but most things can be done with these
three and so by default the others do not appear.  This section of the
manual introduces some basic concepts that are used throughout the rest
of the manual and describes the *Main* panel.


Geomview can display an arbitrary number of objects simultaneously.  The
*TARGET* browser in the *Main* panel displays a list of all
the objects that Geomview currently knows about.  This browser has a
line for each object that you have loaded, plus some lines for other
objects.  One of the other objects is called `World' and corresponds to
the all the currently loaded objects, treated as if they were one
object.  Most of the operations that you can do to one object, such as
applying a motion or changing a color, can also be done to the "World"
object.

The *TARGET* browser also has an entry for each camera.  By
default there is only one camera; it is possible to add more of them via
the *Camera* panel.  Geomview treats cameras in much the same way
as it does geometric objects.  For example, you can move cameras around
and add them and delete them just as with geometric objects.  Cameras do
not usually show up in the display as an object that you see.  Each
camera has a separate camera window which displays the view as seen by
that camera.  (It is possible for each camera to display a geometric
representation of other cameras; *Note Cameras::.)

Because Geomview treats cameras and geometric objects very similarly,
the term "object" in this documentation is used to refer to either
one.  When we need to distinguish between the two kinds of objects, we
use the term "geom" to denote a geometric object and the word
"camera" to denote a camera.

The object which is selected (highlighted) in the *TARGET*
browser is called the "target" object.  This is the object that
receives any actions that you do with the mouse or keyboard.  You can
change the target object by selecting a different line in the
*TARGET* browser.  Another way to change the target object is
to put the mouse cursor directly over a geom in a camera window
and rapidly double-click the right mouse button.  This process is called
"picking"; the picked object becomes the new target.

Geomview objects are all known by two names, both of which are shown in
the *TARGET* browser.  The first name given there, which appears
in square brackets ([ ]), is a short name assigned by Geomview when you
load the object.  It consists of the letter `g' for geoms and `c' for
cameras, followed by a number.  The second name is a longer more
descriptive name; by default this is the name of the file that the
object was loaded from.  The two names are equivalent as far as Geomview
is concerned; at any point where you need to specify a name you can give
either one.

To manipulate an object, make sure you that the object you want to move is the
target object, and put the mouse cursor in a camera window.  Motions are
applied by holding down either the left or middle mouse button and
moving the mouse.  There are several different motion "modes", each for
applying a different kind of motion.  The *MOTION MODE* browser
in the *Main* panel indicates the current motion mode.  The
default is "Rotate".  You can change the current motion mode by
selecting a new one in the *MOTION MODE* browser, or by using the
*Tools* panel.  For more information about motion modes,
*Note Mouse Motions::.

The *Load* button on the *Main* panel brings up the
*Files* panel for loading a file.  The file can contain either a
geom, a camera, or gcl commands.  For details, *Note Loading::.

The *Delete* button causes the target
object to be deleted.  Geomview selects another object to be the new
target.  You can delete cameras as well as geoms in this way.  If you
hit the *Delete* button while the target object is "World",
Geomview deletes all geoms.

The *Panels* browser on the *Main* panel lists all the
Geomview panels.  Click on a panel's entry to bring that panel up.

The *Modules* browser lists Geomview external modules.  An
external module is a separate program that interacts with Geomview to
extend its functionality.  For information on external modules,
*Note Modules::.

The three buttons at the bottom of the *Main* panel, labeled
*Euclidean*, *Hyperbolic*, and *Spherical*, allow
you to change the geometry of the space that Geomview displays.  By
default *Euclidean* is selected.  For details about using
*Hyperbolic* and *Spherical* spaces, *Note Non-Euclidean Geometry::.

Most actions that you can do through Geomview's panels have equivalent
keyboard shortcuts so that you can do the same action by typing a
sequence of keys on the keyboard.  This is useful for advanced users who
are familiar with Geomview's capabilities and want to work quickly
without having to have lots of panels cluttering up the screen.
Keyboard shortcuts are usually indicated in square brackets ([ ]) near
the corresponding item in a panel.  For example, the keyboard shortcut
for *Rotate* mode is 'r'; this is indicated by "[r]" appearing
before the word "Rotate" in the *MOTION MODE* browser.  To
use this keyboard shortcut, just hit the `r' key while the mouse
cursor is in any Geomview window.  Do not hit the `RET' key
afterwards.

Some keyboard shortcuts consist of more than one key.  In these cases
just type the keys one after the other, with no `RET'
afterwards.  Keyboard shortcuts are case sensitive.

The *keyboard* field in the upper left corner of the *Main*
panel echos the current state of keyboard shortcuts.

The button labeled *?* near the top right corner of the
*Main* panel causes Geomview to print out a list of all keyboard
shortcuts to standard output.

The *Quit* button on the main panel terminates Geomview.



File: geomview  Node: Loading, Prev: Basic Interaction, Up: Interaction, Next: Mouse Motions

Loading Objects Into Geomview
=============================

There are several ways to load an object into Geomview.

the *Files* panel
     If you click the *Load* button in Geomview's *Main* panel,
     the *Files* panel will appear.

     This panel lets you select a file from a variety of directories.
     The short browser at the top of the panel shows the selected
     directory, and the longer browser beneath it shows the files in
     that directory.  To select a file, click on it.  After a file is
     selected, you can load it into Geomview by clicking either the
     *Add* or *Replace* button.  The *Add* button causes Geomview to
     load the file as a new object; a new entry will appear in the
     *Objects* browser in the *Main* panel, and all objects currently
     loaded will remain unchanged.  The *Replace* button causes Geomview
     to replace the current object with the object in the selected file.
     If the current object is the *World*, Geomview deletes all objects
     and loads the one in the file as a new object.  If the current
     object is a camera, the *Replace* button has no effect.

     If the file that you select contains gcl commands rather than an
     OOGL object, the *Add* and *Replace* buttons both cause
     Geomview to interpret the commands in the file.  For more information
     about this, *Note GCL::.

     When the *Files* panel first appears, the directory selected in the
     directory browser is the current directory --- the one from which you
     invoked Geomview.  The file browser shows *all* the files in this
     directory, including ones that are not Geomview files.  If you try to
     load a file that doesn't contain either an OOGL object or Geomview
     commands, Geomview will print out an error message.

     The directory browser also lists a second and third directory in
     addition to the current directory.  The second one, which ends in
     `data/geom', is the Geomview example data directory.  This contains
     a wide variety of sample objects.  It also contains several
     subdirectories.  In particular, the `hyperbolic' and
     `spherical' subdirectories have sample hyperbolic and spherical
     objects, respectively.  Directory entries in the browser look just like
     file entries; to view a subdirectory, click on it.

     The third directory shown in the directory browser, which ends in
     `geom', contains several subdirectories with other Geomview files
     in them.  These are used less frequently than the ones in the
     `data/geom' directory.

     You can change the list of directories shown the *Files*
     panel's directory browser by using the `set-load-path' command;
     *Note GCL::.

the `<' keyboard shortcut:
     If you type `<' in any Geomview window, the *Load* panel will
     appear.  This is a small version of the *Files* panel; it contains
     a text field in which you can enter the name of a file to load.  After
     typing the name of the file to load, type `RET'; Geomview will
     load the file as if you had loaded it with the *Add* button in
     the *Files* panel.  If, after bringing up the small load panel
     with `<', you decide you want to use the larger *Files* panel
     after all, press the *Files Browser* button.

geometry loading commands:
     The `load', `geometry', `new-geometry', and `read' gcl commands
     allow you to load an object into Geomview; *Note GCL::.



File: geomview  Node: Mouse Motions, Prev: Loading, Up: Interaction, Next: Point of Interest

Using the Mouse to Manipulate Objects
=====================================

Geomview lets you manipulate objects with the mouse.  There are six
different mouse motion modes: *Rotate*, *Translate*, *Cam Fly*, *Cam
Zoom*, *Geom Scale*, and *Cam Orbit*.  The tools panel has a button for
each of these modes; to switch modes, click on the corresponding button.
You can also select these through the *Motion Mode* browser on the
*Main* panel.

This section describes basic mouse interaction.  There are some more
advanced features available on the *Obscure* panel.  For details,
*Note Command Obscure::.


Each of the motion modes uses a common paradigm for how the motion is
applied.  In particular, each depends on the current *target*
object and the current *center* object.  These are explained in the
following paragraphs.

The current target object is shown in the *Target* field in the
*Tools* panel.  This is the same as the selected object in the
*TARGET OBJECTS* browser in the *Main* panel, and you can
change it by either selecting a new object in the browser, by typing
a new entry in the field, or by picking an object in a camera
window by double-clicking the right mouse button with the cursor over
the object.

The current center object is shown in the *Center* field in the
*Tools* panel.  Its default value is the special word "target",
which means that the center object is whatever the target object is.
You can change the center to any object by typing it in the *Center*
field.  The origin of the center object is held fixed in *Rotate* and
*Orbit* modes.  Normally the center object is one of the existing
geoms listed in the *TARGET OBJECTS* browser, and the actual center of
rotations is the origin of that object's coordinate system.
It is possible, however, to select an arbitrary point of interest on
an object as the center. For details, *Note Point of Interest::.

You apply a mouse motion by holding down either the left or middle mouse
button with the cursor in a camera window and moving the mouse.  Most of
the modes have *inertia*, which means that if you let go of the
button while moving the mouse, the motion will continue.  It may be
helpful to imagine the mouse cursor as being a gripper; when you hold a
mouse button down, it grips the target object and you can move it.  When
you let go of the mouse button, the gripper releases the object.
Letting go of the mouse button while moving the mouse is like throwing
the object --- the object continues moving independent of the mouse.
Inertia can be turned off; see the button on the *Obscure* panel.

Most of the mouse motions have a slow motion version which you get by
holding down the shift key while doing the motion as usual.  This
is useful for finer control.

You can pick any point on an object (not just its origin) as the center of
motion by holding down the shift key while clicking the right mouse button;
this chooses a point of interest.


*Rotate*
     In *Rotate* mode, hold the left mouse button down to rotate the
     target object about the center object.  Rotation proceeds in the
     direction that you move the mouse.  Specifically, the axis of rotation
     passes through the origin of the center object, is parallel to the
     camera view plane, and is perpendicular to the direction of motion of
     the mouse.  When the center is "target", this means that the target
     object rotates about its own origin.

     The middle mouse button in *Rotate* mode rotates the target
     object about an axis perpendicular to the view plane.

*Translate*
     In *Translate* mode, hold the left mouse button down to translate
     the target object in the direction of mouse motion.  The middle mouse
     button translates the target along an axis perpendicular to the view
     plane.

     In Euclidean space, the center object is essentially irrelevant for
     translations.  In hyperbolic and spherical spaces, where translations
     have a unique axis, this axis is chosen to go through the origin of the
     center object.

*Cam Fly*
     *Cam Fly* is a crude flight simulator that lets you fly around
     the scene.  It works by moving the camera.
     Move the mouse while holding the left mouse button down to
     point the camera in a different direction.  To move forward or backward,
     hold down the middle button and move the mouse vertically.  Both of
     these motions have inertia; typically the easiest way to fly around a
     scene is to give the camera a slight forward push by letting go of the
     middle button while moving the mouse upward, and then using the left
     button to steer.

     *Cam Fly* affects the camera window that the mouse is in; it
     ignores the target object and the center object.

*Cam Orbit*
     *Cam Orbit* mode lets you rotate the current camera around the
     current center. The left mouse button does this rotation.  The middle
     mouse button in *Cam Orbit* mode is the same as it is in
     *Cam Fly* mode: it moves the camera forward or backward.

     In general *Cam Orbit* does not move the target object, although
     if the current camera is selected as the target and the center is also
     the target, it will rotate that camera about itself just as in
     *Cam Fly* mode.

*Cam Zoom*
     *Cam Zoom* mode lets you change the current camera's field of
     view with the mouse; hold the left mouse button down and move the mouse
     to change it.  The numeric value of the field of view is shown in the
     *FOV* field in the *Camera* panel.

*Geom Scale*
     *Geom Scale* mode lets you enlarge or shrink a geom.  It operates
     on the target object if that object is a geom.  If the target is a
     camera, *Geom Scale* operates on the geom that was most recently
     the target object.  Moving the mouse while holding down the left mouse button
     scales the object either up or down, depending on the direction of
     mouse motion.  The center of the applied scaling transformation is the
     center object.

     Scaling is meaningful only in Euclidean space; attempts to scale are
     ignored in other spaces.


     *Geom Scale* mode does not have inertia.


The *Stop*, *Look At*, *Center*, and *Reset*
buttons on the *Tools* panel perform actions related to motions
but do not change the current motion mode.



*Stop*
     The *Stop* button causes all motions to stop.  It affects all
     moving objects; not just the target object.  It's keyboard shortcut
     is `H'.

     The keyboard command `h', which does not correspond to a
     panel button, stops the current motion for the target object only.

*Look At*
     The *Look At* button causes the current camera to be moved
     to a position such that it is looking at the target object, and such
     that the target object more or less fills the window.

     The Look At command is unreliable in non-Euclidean spaces.

*Center*
     The *Center* button undoes the target object's transformation,
     moving it back to its home position, which is where it was when you
     originally loaded it into Geomview.

*Reset*
     The *Reset* button stops all motion and causes all objects to
     move back to their home positions.


The other four buttons on the *Tools* panel are:


*MAIN*
     This button brings up the *Main* panel in case you have dismissed it
     or in case it is buried underneath other panels.

*Done*
     This button dismisses the *Tools* panel.  You can bring the panel
     back by selecting it in the *More Panels* browser in the *Main*
     panel, or via the `P t' keyboard shortcut.

*Load*
     This is the same as the *Load* button on the *Main* panel;
     it brings up the *Files* panel.

*Save*
     This is the same as the *Save* button on the *Main* panel;
     it brings up the *Save* panel.



File: geomview  Node: Point of Interest, Prev: Mouse Motions, Up: Mouse Motions, Next: Appearance

Selecting a Point of Interest
-----------------------------

It is sometimes useful to specify a particular point on some object in a
geomview window as the center point for mouse motions.  You can do this
by shift-clicking the right mouse button (i.e. click it once
while holding down the shift key on the keyboard) with the cursor over
the desired point.  This point then becomes the *point of
interest*.  The point of interest must be on an existing object.

Selecting a point of interest simplifies examining a small portion of a
larger object.  Shift-right-click on an interesting point, and select
*Orbit* mode.  Use the middle mouse button to approach, and the
left mouse to orbit the point, examining the region from different
directions.

When you have selected a point of interest, the current center object
changes to an object named "CENTER", which is an invisible object
located at the point of interest.  In addition, mouse motions for the
window in which you made the selection are adjusted so that the point of
interest follows the mouse.

You can change the point of interest at any time by selecting a new one
by shift-clicking the right mouse button again.  You can cancel
the point of interest altogether by shift-clicking the right
mouse button with the cursor on the background (i.e. not on any object).
This changes the center object back to its default value, "target".

The object named "CENTER", which serves as the center object for the
point of interest, is a special kind of geom called an "alien".  It does
not appear in the *TARGET OBJECTS* browser.  By default it has no
geometry associated with it and hence is invisible.  You can, however,
explicitly give it some geometry using a GCL command, causing it to
appear.  Use the `geometry' command for this: `(geometry
CENTER GEOMETRY)', where GEOMETRY is any valid geometry.
For example, `(geometry CENTER { < xyz.vect })' causes the file
`xyz.vect', which is one of the standard example files distributed
with geomview, to be used at the geometry for CENTER.


What actually happens internally when you select a point of interest is
that the center is set to the object called CENTER, and that object is
positioned at the point of interest.  In addition, in order for mouse
motions to track the point of interest, the current camera's focal
length is set to be the distance from the camera to the point of
interest.  You can accomplish this via GCL with the following commands:
     (if (real-id CENTER) nil (new-alien CENTER {}))
     (ui-center CENTER)
     (transform-set CENTER universe universe translate X Y Z)
     (merge camera CAM-ID { focus D })
where `(X,Y,Z)' are the (universe) coordinates of
the point of interest, and D is the distance from that point to
the current camera, CAM-ID.  The first command above creates the
"alien" CENTER if it does not yet exist.


File: geomview  Node: Appearance, Prev: Point of Interest, Up: Interaction, Next: Appearance Panel

Changing the Way Things Look
============================

Geomview uses a hierarchy of appearances to control the way things look.
An "appearance" is a specification of information about how
something should be drawn.  This can include many things such things as
color, lighting, material properties, and more.  Appearances work in a
hierarchal manner: if a certain appearance property, for example face
color, is not specified in a particular object's appearance, that object
is drawn using that property from the parent appearance.  If both the
parent and the child appearance specify a property, the child's setting
takes precedence unless the parent appearance is set to override.

Every geom in Geomview has an appearance associated with it.  There is
also an appearance associated with the "World" geom, which serves as the
parent of each individual geom's appearance.  Finally, there is an
global "base" appearance, which is the parent of the World appearance.

The base appearance specifies reasonable values for all appearance
information, and by default none of the other appearances specify
anything, which means they inherit their values from the base
appearance.  This means that by default all objects are drawn using the
base appearance.

If you change a certain appearance property for a geom, that property
is used in drawing that geom.  The parent appearance is used for any
properties that you do not explicitly set.

Geomview has three panels which let you modify appearances.

* Menu:

* Appearance Panel::    Color etc.
* Materials Panel::    Surface Material properites.
* Lighting Panel::    Lighting Parameters.


File: geomview  Node: Appearance Panel, Prev: Appearance, Up: Appearance, Next: Materials Panel

The Appearance Panel
--------------------

The *Appearance* panel lets you change most common appearance
properties of the target object.
If the target is an individual geom, then changes you make in the
appearance panel apply to that geom's appearance.  If the target is the
World, then appearance panel changes apply to the World appearance
*and* to all individual geom appearances.  (Users have found that
this is more desirable than having the changes only apply to the World
appearance.)  If the target is a camera, then appearance panel changes
apply to the geom that was most recently the target.

The five buttons near the upper right corner under the word
*Draw* control what parts of the target geom are drawn.


*Faces*
     This button specifies whether faces are drawn.

*Edges*
     This button specifies whether edges are drawn.

*BBox*
     This button specifies whether the bounding box is drawn.

*Vects*
     This button specifies whether VECT objects are drawn.  VECTs are a type
     of OOGL object that represent points and line segments in 3-space;
     they are distinct from edges of other kinds of objects, and it is sometimes
     desirable to have separate control over whether they are drawn.

*Normals*
     This button specifies whether surface normal vectors are drawn.


The four buttons under *COLOR* labeled *Faces*, *Edges*,
*Normals*, and *BBox* let you specify the color of
the corresponding aspect of the target geom.  Clicking on one
of them brings up a color chooser panel.
The black dot in the center of the hexagon represents the current color;
you can move it around by dragging it with the left mouse button down.
The slider specifies the intensity.  To accept the color that you have
chosen, click the *OK* button.  To cancel your color selection
and return to the previous color, click the *Cancel* button.

The *SHADING* browser lets you specify the shading model that
Geomview uses to paint the target geom.


*Constant*
     Every face of the object is drawn with a constant color which does not
     depend on the location of the face, the camera, or the light sources.
     If the object does not contain per-face or per-vertex colors, the
     diffuse color of the object's appearance is used.  If the object
     contains per-face colors, they are used.  If the object contains
     per-vertex colors, each face is painted using the color of its first
     vertex.

*Flat*
     Each face of the object is drawn with a color that depends on the
     relative location of the face, the camera, and the light sources.
     The color is constant across the face but may change as the face,
     camera, or lights move.

*Smooth*
     Each face of the object is drawn with smoothly interpolated colors based
     on the normal vectors at each vertex.  If the object does not contain
     per-vertex normals, this has the same effect as flat shading.  If the
     object has reasonable per-vertex normals, the effect is to smooth
     over the edges between the faces.

*CSmooth*
     Each face of the object is drawn with exactly the specified color(s),
     independent of lighting, orientation, and material properties.  If the
     object is defined with per-vertex colors, the colors are interpolated
     smoothly across the face; otherwise the effect is the same as in
     Constant shading style.


The *Facing Normals* button on the *Appearance* panel
indicates whether or not Geomview should arrange that normal vectors
always face the viewer.  If a normal vector points away from the viewer
the color of the corresponding face or vertex usually is darker than is
desired.  Geomview can avoid this by using the opposite normal in
shading calculations.  This is the default.  To change it so that the
actual normals are used, press this button.  This has no effect in
constant shading mode.

The three text fields in the lower left corner of the *Appearance*
panel are:


*Line Width*
     The width, in pixels, for lines drawn by Geomview.

*Normal Length*
     This is actually a scale factor; when normal vectors are drawn, Geomview
     draws them to have a length that is their natural length times this
     number.

*Patch Dicing*
     Geomview draws Bezier patches by first converting them to meshes.  This
     parameter specifies the resolution of the mesh: if *Patch Dicing*
     is N, then an N by N mesh is used to draw each Bezier
     patch.  if *Patch Dicing* is 1, the resolution reverts to a
     built-in default value.


The *Revert* button on the *Appearance* panel undoes all
settings in the target appearance.  This causes the target geom to
inherit all its appearance properties from its parent.

The *Appearance* panel's *Override* button determines whether
appearance controls should override settings in the objects themselves --
for example, setting the face color will affect all faces of objects with
multi-colored facets.  Otherwise, appearance controls only provide settings
which the objects themselves do not specify.
By default, *Override* is enabled.  This button applies to all objects,
and to all appearance-related panels.


File: geomview  Node: Materials Panel, Prev: Appearance Panel, Up: Appearance, Next: Lighting Panel

The Materials Panel
-------------------

The *Materials* panel controls material properties of surfaces.
It works with the target object in the same way that the
*Appearance* panel does.


*Transparent*
     This button determines whether transparency is enabled.  Geomview
     does not fully support transparency yet and on some machines it does
     not work at all.

*Alpha*
     This slider determines the opacity/transparency when transparency is
     enabled.  0 means totally transparent, 1 means totally opaque.

*Diffuse Reflectance*
     This slider controls the diffuse reflectance of a surface.  This has
     to do with how much the surface scatters light that it reflects.

*Shininess*
     This slider controls how shiny a surface is.   This determines the
     size of specular highlights on the surface.  Lower values give the
     surface a duller appearance.

*Ambient Reflectance*
     This slider controls how much of the ambient light a surface reflects.

*Specular Reflectance*
     This slider controls the specular reflectance of a surface.  This
     has to do with how directly the surface reflects light rays.  Higher
     values give brighter specular highlights.

*Done*
     This button dismisses the *Materials* panel.



File: geomview  Node: Lighting Panel, Prev: Materials Panel, Up: Appearance, Next: Cameras

The Lighting Panel
------------------

The *Lighting* panel controls the number, position, and color of
the light sources used in shading.

The *Lighting* panel is different from the *Appearance* and
*Material* panels in that it always works with the base
appearance.  This is because it usually makes sense to use the same set
of lights for drawing all objects in your scene.


*LIGHTS*
     The *LIGHTS* browser shows the currently selected light.  Changes
     made using the other widgets on this panel apply to this light.  There
     is always at least one light, the ambient light.

*Intensity*
     This slider controls the intensity of the current light.

*Color*
     This button brings up a color chooser which lets you select the color
     of the current light.

*Add*
     This button adds a light.

*Delete*
     This button deletes the current light.

*Show Lights*
     This button lets you see and change the positions of the light sources
     in a camera window.  Each light is drawn as long cylinder which is
     supposed to remind you of a light beam.  When you click on the
     *Show Lights* button Geomview goes into "light edit" mode, during
     which you can rotate current light by holding down the left mouse button
     and moving the mouse.  Lights placed in this way are infinitely distant,
     so what you are changing is the angular position.  Click on the
     *Show Lights* button again to return to the previous motion mode
     and to quit drawing the light beams.

*Done*
     This button dismisses the *Lighting* panel.


Geomview's *Appearance*, *Materials*, and *Lighting*
panels are constructed to allow you to easily do most of the appearance
related things that you might want to do.  The appearance hierarchy that
Geomview supports internally, however, is very complex and there are
certain operations that you cannot do with the panels.  The Geomview
command language (gcl) provides complete support for appearance operations.
In particular, the `merge-baseap' command can be used to change the
base appearance (which, except for lighting, cannot be changed by
Geomview's panels).  The `merge-ap' command can be used to change
an individual geom's appearance.  Appearances can also be specified in
OOGL files; for details, *Note Appearances::.